# 进阶教程

```{admonition} 本文引用的文件
:class: note

- [random.rst](../../../../products/mpython/tutorials/advance/random.rst)
- [filesystem.rst](../../../../products/mpython/tutorials/advance/filesystem.rst)
- [timer.rst](../../../../products/mpython/tutorials/advance/timer.rst)
- [radio.rst](../../../../products/mpython/tutorials/advance/radio.rst)
- [i2c.rst](../../../../products/mpython/tutorials/advance/i2c.rst)
- [thread.rst](../../../../products/mpython/tutorials/advance/thread.rst)
- [bme280.rst](../../../../products/mpython/tutorials/advance/bme280.rst)
- [iot/index.rst](../../../../products/mpython/tutorials/advance/iot/index.rst)
- [iot/mqtt.rst](../../../../products/mpython/tutorials/advance/iot/mqtt.rst)
- [iot/bigiot.rst](../../../../products/mpython/tutorials/advance/iot/bigiot.rst)
- [iot/yeelight.rst](../../../../products/mpython/tutorials/advance/iot/yeelight.rst)
```

## 产品概述
本教程面向mPython掌控板（ESP32）与ESP32-S3平台的进阶学习者，围绕随机数、文件系统、定时器、无线广播、I2C、线程、BME280传感器与物联网八大主题，提供从概念到实践的系统化指导。通过示例代码与平台API说明，帮助读者掌握在资源受限的嵌入式环境中进行数据采集、本地存储、并发控制与网络通信的综合能力，适用于创客教育、智能家居、环境监测与轻量物联网应用等场景。

## 核心业务流程
- 数据采集：通过I2C总线读取外部传感器数据（如SHT20），或通过板载BME280获取温湿度与气压；结合随机数生成用于仿真或交互效果。
- 定时与并发：使用定时器周期性触发任务；使用线程实现多任务并行处理，并通过锁保护共享资源。
- 本地存储：利用MicroPython文件系统读写文本或二进制数据，持久化配置与采集结果。
- 设备间通信：使用2.4G无线广播模块进行短距离组网通信；通过MQTT协议接入云平台；对接贝壳物联与Yeelight生态完成远程控制。
- 可视化与反馈：将数据展示在OLED/TFT屏上，或通过RGB灯、蜂鸣器等外设反馈状态。

```text
flowchart TD
A["开始"] --> B["初始化: I2C/Timer/Thread/WiFi"]
B --> C{"采集源"}
C --> |I2C传感器| D["读取SHT20温度/湿度"]
C --> |板载BME280| E["读取温度/湿度/气压"]
C --> |随机数| F["生成随机值(演示/仿真)"]
D --> G["数据处理与格式化"]
E --> G
F --> G
G --> H["显示/记录/发送"]
H --> I{"输出方式"}
I --> |本地| J["写入文件系统/屏幕显示"]
I --> |远程| K["MQTT发布/贝壳物联/局域网控制"]
J --> L["结束"]
K --> L
```

## 功能模块清单
- 随机数模块
  - 职责：提供随机选择、范围随机、浮点随机与种子控制，支持可重复随机序列。
  - 用户价值：用于游戏逻辑、随机提示、仿真数据与动画效果。
  - 验收要点：能正确返回指定范围的整数/浮点数；设置种子后序列可重现。
- 文件系统
  - 职责：提供open、read/write、os.listdir/remove等接口，支持文本与二进制文件操作。
  - 用户价值：持久化配置、日志与测量数据；模块化组织脚本（boot.py/main.py）。
  - 验收要点：能创建/读取/删除文件；with上下文自动关闭；列表与统计可用。
- 定时器
  - 职责：基于硬件定时器周期回调，驱动音乐、轮询与心跳保活。
  - 用户价值：精确时间控制、非阻塞任务调度。
  - 验收要点：ONE_SHOT/PERIODIC模式正确；回调按时触发；value()计数准确。
- 无线广播
  - 职责：2.4G射频收发，支持频道、包长、功率与速率配置。
  - 用户价值：设备间近场组网、简易对讲与电报机。
  - 验收要点：同频道收发成功；receive(True)可获MAC；config参数生效。
- I2C
  - 职责：主从通信，writeto/readfrom配合传感器协议读取原始数据并换算。
  - 用户价值：扩展各类I2C传感器与外设。
  - 验收要点：地址与命令正确；延时满足器件要求；数据转换公式准确。
- 线程
  - 职责：_thread启动多线程，time.sleep控制节奏；Lock保护共享变量。
  - 用户价值：并发执行多个任务，提升响应性。
  - 验收要点：多任务交替打印；加锁后临界区串行执行；无死锁与异常释放。
- BME280传感器
  - 职责：读取温度、湿度、气压，单位换算与刷新显示。
  - 用户价值：环境感知与高度计应用。
  - 验收要点：温度/湿度/气压数值合理；刷新频率稳定；未贴片时可用外置模块。
- 物联网
  - 职责：MQTT发布订阅、贝壳物联设备通讯、Yeelight局域网控制。
  - 用户价值：云端数据上报、远程控制与智能家居联动。
  - 验收要点：连接/订阅/发布正常；回调触发；设备在线与指令可达。

**章节来源**
- [random.rst:1-103](../../../../products/mpython/tutorials/advance/random.rst)
- [filesystem.rst:1-178](../../../../products/mpython/tutorials/advance/filesystem.rst)
- [timer.rst:1-45](../../../../products/mpython/tutorials/advance/timer.rst)
- [radio.rst:1-57](../../../../products/mpython/tutorials/advance/radio.rst)
- [i2c.rst:1-106](../../../../products/mpython/tutorials/advance/i2c.rst)
- [thread.rst:1-113](../../../../products/mpython/tutorials/advance/thread.rst)
- [bme280.rst:1-41](../../../../products/mpython/tutorials/advance/bme280.rst)
- [iot/index.rst:1-102](../../../../products/mpython/tutorials/advance/iot/index.rst)
- [iot/mqtt.rst:1-208](../../../../products/mpython/tutorials/advance/iot/mqtt.rst)
- [iot/bigiot.rst:1-115](../../../../products/mpython/tutorials/advance/iot/bigiot.rst)
- [iot/yeelight.rst:1-138](../../../../products/mpython/tutorials/advance/iot/yeelight.rst)

## 数据与状态
- 传感器数据流
  - I2C路径：主机发起读命令 → 等待器件就绪 → 读取原始字节 → 按手册公式换算为物理量 → 显示/存储/上报。
  - BME280路径：直接调用封装API获取温度/湿度/气压 → 单位换算（Pa→kPa） → 刷新显示。
- 随机数状态
  - 通过seed固定随机序列，保证可重复行为；randint/randrange/random/uniform覆盖常用场景。
- 定时器状态
  - 计数器递增；回调函数中执行任务；value()可查询当前计数；PERIODIC模式下循环触发。
- 线程状态
  - 多任务并发；共享变量需加锁；sleep控制节奏；线程结束时显式退出。
- 文件系统状态
  - 平面文件系统；with上下文确保文件关闭；listdir/remove/stat管理元信息。
- 无线广播状态
  - 通道/队列/功率/速率配置；发送字符串或字节；接收可选携带MAC。
- 物联网状态
  - MQTT：Broker-Publisher-Subscriber模型；主题分层；keepalive保活；回调处理消息。
  - 贝壳物联：设备上线check_in；say回调接收消息；update上传数据。
  - Yeelight：discover_bulbs发现设备；TCP控制开关/亮度/颜色/色温。

```text
sequenceDiagram
participant S as "传感器"
participant M as "主控(mPython)"
participant T as "定时器"
participant FS as "文件系统"
participant N as "网络(MQTT/贝壳/Yeelight)"
participant O as "显示/外设"
T->>M : 周期回调
M->>S : I2C读/或BME280读取
S-->>M : 原始数据/已换算数据
M->>M : 数据校验/单位换算
M->>FS : 写入日志/配置
M->>N : 发布主题/上报数据/控制设备
N-->>M : 确认/回调
M->>O : 更新屏幕/指示灯/声音
```

**章节来源**
- [i2c.rst:22-106](../../../../products/mpython/tutorials/advance/i2c.rst)
- [bme280.rst:12-30](../../../../products/mpython/tutorials/advance/bme280.rst)
- [timer.rst:14-41](../../../../products/mpython/tutorials/advance/timer.rst)
- [thread.rst:11-113](../../../../products/mpython/tutorials/advance/thread.rst)
- [filesystem.rst:28-149](../../../../products/mpython/tutorials/advance/filesystem.rst)
- [radio.rst:14-31](../../../../products/mpython/tutorials/advance/radio.rst)
- [iot/mqtt.rst:77-148](../../../../products/mpython/tutorials/advance/iot/mqtt.rst)
- [iot/bigiot.rst:28-101](../../../../products/mpython/tutorials/advance/iot/bigiot.rst)
- [iot/yeelight.rst:52-112](../../../../products/mpython/tutorials/advance/iot/yeelight.rst)

## 关键约束与边界
- 硬件与引脚
  - I2C总线使用P19(SCL)、P20(SDA)，注意与其他外设冲突。
  - 部分引脚（如P4光线、P10声音）不可作为通用GPIO。
- 时序与延时
  - I2C传感器需要等待测量完成（如SHT20温度约70ms、湿度约25ms），否则读数无效。
  - 定时器回调中避免耗时操作，必要时仅置标志位由主循环处理。
- 并发与同步
  - 多线程共享变量必须加锁，防止竞态条件；锁释放需在锁定状态下调用。
- 网络与平台限制
  - MQTT keepalive需合理设置，避免频繁断连；不同平台端口可能不同。
  - Yeelight局域网控制存在连接数与指令配额限制（每分钟60条，局域网总配额144）。
- 存储与生命周期
  - MicroPython文件系统为平面结构，无目录层级；with语句确保文件及时关闭。
  - boot.py先于main.py执行，适合初始化与引导逻辑。
- 传感器可用性
  - 标准掌控板默认未贴BME280芯片，需使用外置模块通过I2C接入。

**章节来源**
- [i2c.rst:35-67](../../../../products/mpython/tutorials/advance/i2c.rst)
- [bme280.rst:7-11](../../../../products/mpython/tutorials/advance/bme280.rst)
- [thread.rst:79-113](../../../../products/mpython/tutorials/advance/thread.rst)
- [timer.rst:29-41](../../../../products/mpython/tutorials/advance/timer.rst)
- [filesystem.rst:21-25](../../../../products/mpython/tutorials/advance/filesystem.rst)
- [iot/mqtt.rst:92-104](../../../../products/mpython/tutorials/advance/iot/mqtt.rst)
- [iot/yeelight.rst:129-133](../../../../products/mpython/tutorials/advance/iot/yeelight.rst)